:- module(remote_tools).
:- export attach_tools / 4.
:- export attach_tools / 3.
:- export attached / 1.
:- export attach_tools / 0.
:- export tools / 0.
:- comment(summary, "Allow the Tk development tools to be used remotely").
:- comment(desc, "This library allows the Tk development tools to be used via the remote Tcl\ninterface. This allows the development tools to be used by any ECLiPSe\nsession, and not just one which uses the embedded Tcl interface.").
:- comment(attach_tools / 0, [summary : "Initiate the attachment of remote development tools", desc : html("   <P>Initiate the attachment of the remote development tools. This will create\n   a connection waiting for the remote development tools to be attached to.\n   It will print the hostname and the port number that should be given to\n   the development tools. The remote development tools should be started \n   and supplied with the hostname and port number. Once this is done, the\n   development tools are ready to be used. Control is initially given back\n   to ECLiPSe when the tools have been attached."), resat : no, fail_if : "Development tools already attached.", see_also : [tools / 0, attach_tools / 3]]).
:- comment(attach_tools / 3, [summary : "A flexible attachment of remote development tools", amode : attach_tools(?, ++, ?), args : ["Address" : "Address for the remote connection (Host/Port or variable)", "TimeOut" : "Time-out interval (int/float or the atom block)", "Goal" : "Goal to execute during connection"], desc : html("\n   <P>Initiate the attachment of the remote development tools, providing the\n   user with more control over the connection than attach_tools/0. The\n   predicate will create a connection waiting for the remote development\n   tools to be attached to.  It will then execute Goal and then tries to\n   complete the connection by waiting at most TimeOut seconds for the\n   remote development tools to connect.  If TimeOut is the atom block, then\n   it will wait indefinitely.\n\n   </P><P>Address is the Host/Port address that the remote connection will be\n   made.  This can be left as a variable, so that the system can determine\n   its own address, or the user can specify a specific Port. The main\n   purpose for Goal is to allow the user to start out the remote\n   development tools from it using Address, so that the user does not need\n   to manually connect the remote development tools. Control is initially\n   given back to ECLiPSe when the tools have been attached.\n\n   </P><P>The predicate will fail or throw an exception if Goal respectively fails\n   or throw an exception. It will also fail if it waits more than TimeOut\n   seconds for the remote tools to connect. In these cases, the server\n   socket will be properly closed.\n\n   </P><P>attach_tools/0 can be implemented using attach_tools/3 as follows:\n\n   <PRE>\n         attach_tools :-\n             attach_tools(_, block, true).\n   </PRE>\n   "), eg : "\n    % the following will cause the remote tools to start automatically\n    % if tktools can be run from a shell. It will wait 10 seconds before\n    % failing and closing the server socket.\n    [eclipse 2]:  attach_tools(H/P,10,\n         exec(['tktools','--','-h',H,'-p',P], [], Pid)).\n\n    H = 'cow.icparc.ic.ac.uk'\n    P = 1953\n    Pid = 27678\n    Yes (0.04s cpu)\n    [eclipse 3]:\n   ", resat : no, exceptions : [4 : "Goal or TimeOut are variables", 5 : "TimeOut is not an integer nor float nor atom", 6 : "TimeOut is either too small or large or is an atom other than block"], fail_if : "   Development tools already attached, or waiting TimeOut seconds  \n   for remote tools to connect, or if Goal fails", see_also : [tools / 0, attach_tools / 0]]).
:- comment(attached / 1, [summary : "Checks if remote tools are currently attached or not.", amode : attached(?), args : ["ControlStream" : "control stream (stream name or variable)"], fail_if : "Remote tools are not currently attached.", desc : html("<P>\n\tChecks if the remote development tools have been attached to this \n        ECLiPSe session or not. If attached, the predicate succeeds and \n        returns the stream name of the control stream. If not attached, the\n        predicate fails.")]).
:- comment(tools / 0, [summary : "Transfer control from ECLiPSe to the development tools.", desc : html("<P>\n\tTransfer the `control' from ECLiPSe to the development tools,\n\tallowing the user to use the development tools GUI interactively.\n\tThis predicate returns when control is returned to ECLiPSe.\n<P>\n        Note that some features of the development tools can be triggered\n        without interacting directly with the GUI. For example, placing a\n        spy-point on a predicate will cause the tracer tool to pop-up when\n        the predicate is called.\n"), see_also : [attach_tools / 0, attach_tools / 3], exceptions : [6 : "tools/0 called before development tools have been attached."], resat : no]).
:- comment(attach_tools / 4, hidden).